=over

=item readdir DIRHANDLE
X<readdir>

Returns the next directory entry for a directory opened by
L<C<opendir>|/opendir DIRHANDLE,EXPR>.
If used in list context, returns all the rest of the entries in the
directory.  If there are no more entries, returns the undefined value in
scalar context and the empty list in list context.

If you're planning to filetest the return values out of a
L<C<readdir>|/readdir DIRHANDLE>, you'd better prepend the directory in
question.  Otherwise, because we didn't L<C<chdir>|/chdir EXPR> there,
it would have been testing the wrong file.

    opendir(my $dh, $some_dir) || die "Can't opendir $some_dir: $!";
    my @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
    closedir $dh;

As of Perl 5.12 you can use a bare L<C<readdir>|/readdir DIRHANDLE> in a
C<while> loop, which will set L<C<$_>|perlvar/$_> on every iteration.
If either a C<readdir> expression or an explicit assignment of a
C<readdir> expression to a scalar is used as a C<while>/C<for> condition,
then the condition actually tests for definedness of the expression's
value, not for its regular truth value.

    opendir(my $dh, $some_dir) || die "Can't open $some_dir: $!";
    while (readdir $dh) {
        print "$some_dir/$_\n";
    }
    closedir $dh;

To avoid confusing would-be users of your code who are running earlier
versions of Perl with mysterious failures, put this sort of thing at the
top of your file to signal that your code will work I<only> on Perls of a
recent vintage:

    use 5.012; # so readdir assigns to $_ in a lone while test

=back